openapi: 3.0.1
info:
  title: External Contacts API
  description: >-
    Provides access to the external contacts that are part of a Hyperproof
    organization.
  version: '1.0'
servers:
  - url: https://api.hyperproof.app/v1/externalcontacts
    description: Hyperproof US
  - url: https://api.hyperproof.eu/v1/externalcontacts
    description: Hyperproof EU
  - url: https://api.hyperproofgov.app/v1/externalcontacts
    description: Hyperproof Gov
security:
  - oauth2: []
paths:
  /:
    get:
      summary: Get External Contacts
      description: >+
        `GET /`


        #### Description


        Retrieves details of all external contacts by their unique IDs,
        returning information such as names, emails, and associated Hyperproof
        objects.

      operationId: get-external-contacts
      parameters:
        - name: objectType
          in: query
          description: >-
            If provided, returns all external contacts associated with the
            objectType
          schema:
            enum:
              - vendor
            type: string
        - name: objectId
          in: query
          description: >-
            If provided, returns external contacts associated with the object.
            The objectType parameter is required if objectId is provided.
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalContactCollection'
              example:
                - id: d88d505d-5199-11ee-a644-522476618ae8
                  orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                  givenName: John
                  surname: Smith
                  email: john.smith@example.com
                  status: active
                  objectType: vendor
                  objectId: e99e616e-6211-22ff-b755-633587729bf9
                  createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  createdOn: '2023-09-12T18:26:10.0053650+00:00'
                  updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                  updatedOn: '2023-09-12T18:26:10.0053650+00:00'
                  permissions: []
    post:
      summary: Add External Contact
      description: >+
        `POST /`


        #### Description


        Adds an external contact to a specified Hyperproof object, linking the
        contact’s details for collaboration or reference purposes.

      operationId: add-external-contact
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalContactPost'
            example:
              givenName: John
              surname: Deer
              email: john.deer@example.com
              objectType: vendor
              objectId: e99e616e-6211-22ff-b755-633587729bf9
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalContact'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                givenName: John
                surname: Smith
                email: john.smith@example.com
                status: active
                objectType: vendor
                objectId: e99e616e-6211-22ff-b755-633587729bf9
                createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                createdOn: '2023-09-12T18:26:10.0053650+00:00'
                updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                updatedOn: '2023-09-12T18:26:10.0053650+00:00'
                permissions: []
  /{externalContactId}:
    get:
      summary: Get External Contact
      description: >
        `GET /{externalContactId}`


        #### Description


        Retrieves details of an external contact by their unique ID, returning
        information such as name, email, and associated Hyperproof objects.
      operationId: get-external-contact
      parameters:
        - name: externalContactId
          in: path
          description: Unique ID of the external contact to retrieve.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalContact'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                givenName: John
                surname: Smith
                email: john.smith@example.com
                status: active
                objectType: vendor
                objectId: e99e616e-6211-22ff-b755-633587729bf9
                createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                createdOn: '2023-09-12T18:26:10.0053650+00:00'
                updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                updatedOn: '2023-09-12T18:26:10.0053650+00:00'
                permissions: []
    patch:
      summary: Update External Contact
      description: >+
        `PATCH /{externalContactId}`


        #### Description


        Updates the information of an existing external contact, allowing
        modifications to details such as name, email, or associated Hyperproof
        objects.

      operationId: update-external-contact
      parameters:
        - name: externalContactId
          in: path
          description: Unique ID of the external contact to update.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalContactPatch'
            example:
              givenName: Jane
              surname: Doe
              email: jane.doe@example.com
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalContact'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                givenName: John
                surname: Smith
                email: john.smith@example.com
                status: active
                objectType: vendor
                objectId: e99e616e-6211-22ff-b755-633587729bf9
                createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                createdOn: '2023-09-12T18:26:10.0053650+00:00'
                updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                updatedOn: '2023-09-12T18:26:10.0053650+00:00'
                permissions: []
    delete:
      summary: Delete External Contact
      description: |+
        `DEL /{externalContactId}`

        #### Description

        Removes an external contact from an organization.

      operationId: delete-external-contact
      parameters:
        - name: externalContactId
          in: path
          description: Unique ID of the external contact to delete.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalContact'
              example:
                id: d88d505d-5199-11ee-a644-522476618ae8
                orgId: ce83e3cd-5199-11ee-a644-522476618ae8
                givenName: John
                surname: Smith
                email: john.smith@example.com
                status: active
                objectType: vendor
                objectId: e99e616e-6211-22ff-b755-633587729bf9
                createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                createdOn: '2023-09-12T18:26:10.0053650+00:00'
                updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
                updatedOn: '2023-09-12T18:26:10.0053650+00:00'
                permissions: []
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.hyperproof.app/oauth/token
          scopes:
            externalcontact.read: Grants read access to external contacts
            externalcontact.update: Grants update access to external contacts
  schemas:
    ExternalContact:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the external contact.
        orgId:
          type: string
          description: The unique identifier for the organization.
        givenName:
          type: string
          description: The given name of the external contact.
        surname:
          type: string
          description: The surname of the external contact.
        email:
          type: string
          description: The email address of the external contact.
        objectType:
          type: string
          description: >-
            The type of the Hyperproof object the external contact is associated
            with.
        objectId:
          type: string
          description: >-
            The id of the Hyperproof object the external contact is associated
            with.
        status:
          type: string
          enum:
            - active
            - archived
            - deleted
          description: The status of the external contact.
        createdOn:
          type: string
          format: date-time
          description: The date the external contact was created (ISO-8601 format).
        createdBy:
          type: string
          description: The unique identifier of the user who created the external contact.
        updatedOn:
          type: string
          format: date-time
          description: The date the external contact was updated (ISO-8601 format).
        updatedBy:
          type: string
          description: >-
            The unique identifier of the user who last updated the external
            contact.
        permissions:
          type: array
          description: List of permissions the API user has on the external contact.
          items:
            type: string
      example:
        id: d88d505d-5199-11ee-a644-522476618ae8
        orgId: ce83e3cd-5199-11ee-a644-522476618ae8
        givenName: John
        surname: Smith
        email: john.smith@example.com
        status: active
        objectType: vendor
        objectId: e99e616e-6211-22ff-b755-633587729bf9
        createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        createdOn: '2023-09-12T18:26:10.005365Z'
        updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        updatedOn: '2023-09-12T18:26:10.005365Z'
        permissions: []
    ExternalContactCollection:
      type: array
      items:
        $ref: '#/components/schemas/ExternalContact'
    ExternalContactPost:
      type: object
      properties:
        givenName:
          type: string
          description: The given name of the external contact.
        surname:
          type: string
          description: The surname of the external contact.
        email:
          type: string
          description: The email address of the external contact.
        objectType:
          type: string
          enum:
            - vendor
            - risk
          description: The type of the object to associate the external contact with.
        objectId:
          type: string
          description: >-
            The unique identifier of the Hyperproof object to associate the
            external contact with.
      required:
        - givenName
        - surname
        - email
        - objectType
        - objectId
      example:
        givenName: John
        surname: Deer
        email: john.deer@example.com
        objectType: vendor
        objectId: e99e616e-6211-22ff-b755-633587729bf9
    ExternalContactPatch:
      type: object
      properties:
        givenName:
          type: string
          description: The given name to update to for the external contact.
        surname:
          type: string
          description: The surname to update to for the external contact.
        email:
          type: string
          description: The email address to update to for the external contact.
      example:
        givenName: Jane
        surname: Doe
        email: jane.doe@example.com
